Convert READMEs to markdown by slevis-lmwg · Pull Request #3816 · ESCOMP/CTSM

slevis-lmwg · 2026-03-16T22:31:01Z

Description of changes

See title

Specific notes

Contributors other than yourself, if any:

CTSM Issues Fixed (include github issue #):
Fixes #2761

Are answers expected to change (and if so in what way)?
No

Any User Interface Changes (namelist or namelist defaults changes)?
No

Does this create a need to change or add documentation? Did you do so?
No

Testing performed, if any:
None needed

README_GITFLEXIMOD.md

See if this renders better.

README_GITFLEXIMOD.md

slevis-lmwg · 2026-03-16T22:45:32Z

Note to self: Look for more READMEs that need conversion.

@ekluzek how should we handle the presence of both a README and a README.md in the /ctsm directory?

ekluzek · 2026-03-16T23:30:31Z

@ekluzek how should we handle the presence of both a README and a README.md in the /ctsm directory?

@slevis-lmwg

Good question. The README.md shows up as what you see on github. And it's probably something we want to be short, with the main content being what we want people to see when they got to CTSM on github. In contrast, the content of the README details about how to use CTSM and some practical details about how to get around in the checkout.

So you could add the content of the plain README to the README.md, but make it at the end. The other option would be to have a file with a different name maybe something like: README_on_CTSM.md? Which sounds better to you?

slevis-lmwg · 2026-03-18T00:43:23Z

There are several READMEs to address in cime_config/testdefs/testmods_dirs/clm/* and cime_config/usermods_dirs/clm/*/*that seem lower priority to me.

Next one to work on: python/ctsm/test

UPDATE on the above from a meeting with Erik earlier this afternoon:
We agreed that we do not need to replace the aforementioned "lower priority" READMEs with .md versions of them.

slevis-lmwg · 2026-03-19T21:36:41Z

README_GITFLEXIMOD.md

@ekluzek it occurred to me that maybe I shouldn't be changing .rst files to .md, such as this one (already did it) and README.python_pkgs.rst (I will wait to hear back from you).

I have started answering my own question. Changing the second of these files caused an error in a github workflow. I will see if changing the first file is a problem, too.

I was confusing myself:

The original question still holds, whether it's ok the change README_GITFLEXMOD and README.python_pkgs from .rst to .md

I had to revert a different file from .md to no suffix (plain text) to correct a failing github workflow:
README.unit_testing

This note is related, but it's a reminder to myself:
If we keep README_GITFLEXIMOD.md, I now see additional formatting corrections that I would try.

I would strongly prefer we convert reStructuredText files to Markdown, which is much more human-readable. Having just one markup format would also simplify doc viewing, as users would only need one rendering tool.

slevis-lmwg · 2026-03-19T23:49:48Z

@samsrabin I will send you a review request:

Relatively simple PR, though you may choose to view each file whole to confirm that we still have readable files.
I posed a question for Erik that you may have insight into (see unresolved conversation above).

slevis-lmwg · 2026-03-20T16:21:13Z

src/README.unit_testing.md

I reversed this replacement with a later commit, but now I see that maybe I just needed to update the following:

.github/workflows/docs-build-and-deploy.yml: - 'src/README.unit_testing' .github/workflows/docs.yml: - 'src/README.unit_testing' .github/workflows/docs.yml: - 'src/README.unit_testing' doc/source/users_guide/testing/testing.rst:.. include:: ../../../../src/README.unit_testing

Similarly should I update these (for a file already in .md format):

.github/workflows/docs-build-and-deploy.yml: - 'tools/README' .github/workflows/docs.yml: - 'tools/README' .github/workflows/docs.yml: - 'tools/README'

samsrabin

Great start, Sam, thanks! I've requested some changes and added other comments.

samsrabin · 2026-03-20T18:19:03Z

bld/namelist_files/use_cases/README.md

This file at least appears to be valid Markdown, but it doesn't take advantage of any Markdown features. That's probably acceptable; mark this comment as resolved if you agree.

samsrabin · 2026-03-20T18:20:34Z

bld/README.md

It would be better to use the simpler Markdown syntax for section headings, using #, rather than this underlining method.

samsrabin · 2026-03-20T18:22:10Z

tools/mksurfdata_esmf/README.filecopies.md

The headings could be changed to use Markdown heading syntax (prefix with #, ##), but I don't feel too strongly here.

samsrabin · 2026-03-20T18:25:04Z

tools/modify_input_files/README.mesh_mask_modifier.md

@@ -2,32 +2,41 @@ mesh_mask_modifier is a tool that modifies mesh_mask files. It reads a
 mesh_mask file and outputs a modified copy of the same file.

 Files involved
--------------


"Files involved" should be restored to be a heading.

samsrabin · 2026-03-20T18:25:30Z

tools/modify_input_files/README.mesh_mask_modifier.md

It would be better to use the simpler Markdown syntax for section headings, using #, rather than this underlining method. However, since the underlining method was already used, it's probably not worth the effort.

samsrabin · 2026-03-20T18:26:59Z

README.CHECKLIST.new_case.md

The bulleted lists should not be escaped, and each list item should be all on one line.

samsrabin · 2026-03-20T18:27:55Z

README_GITFLEXIMOD.md

I would strongly prefer we convert reStructuredText files to Markdown, which is much more human-readable. Having just one markup format would also simplify doc viewing, as users would only need one rendering tool.

samsrabin · 2026-03-20T18:29:50Z

README_GITFLEXIMOD.md

Many strange artifacts left over from the conversion from reStructuredText to Markdown, as you can see by clicking the ellipsis > View File. See #3148 for instructions on using pandoc to convert automatically.

samsrabin · 2026-03-20T18:30:43Z

README_on_CTSM.md

-bin/git-fleximod -- Script to manage the needed sub-component source directories (handled with git submodule)
-py_env_create ----- Script to setup the python environment for CTSM python tools using conda
-python ------------ Python modules used in tools and testing and automated checking of ALL CTSM python scripts
+doc --------------- Documentation of CTSM  


Why the deleted periods and added whitespace here and elsewhere?

slevis-lmwg added 3 commits March 16, 2026 16:01

Covert README.CHECKLIST.new_case.md to markdown

896e3da

Remove README.CHECKLIST.new_case now that I added markdown version

58dbce5

Convert README_GITFLEXIMOD.rst to README_GITFLEXIMOD.md

0df9a7b

slevis-lmwg self-assigned this Mar 16, 2026

slevis-lmwg added documentation additions or edits to user-facing documentation or its infrastructure bfb bit-for-bit docs:update Significant update or fix needed to existing documentation docs-loc:other Relates to documentation somewhere not covered by the other docs-loc labels. labels Mar 16, 2026

slevis-lmwg added this to CLM documentation Mar 16, 2026

slevis-lmwg moved this to In Progress in CLM documentation Mar 16, 2026

slevis-lmwg added this to the cesm3.0.0 release branch tag milestone Mar 16, 2026

slevis-lmwg added this to CTSM: Upcoming tags and LMWG: Sprint Planning Board Mar 16, 2026

github-project-automation bot moved this to Todo in LMWG: Sprint Planning Board Mar 16, 2026

github-project-automation bot moved this to Ready to start (or start again) in CTSM: Upcoming tags Mar 16, 2026

slevis-lmwg moved this from Ready to start (or start again) to In progress - b4b-dev in CTSM: Upcoming tags Mar 16, 2026

slevis-lmwg commented Mar 16, 2026

View reviewed changes

README_GITFLEXIMOD.md Outdated Show resolved Hide resolved

Apply suggestion from @slevis-lmwg

8c0d6eb

See if this renders better.

slevis-lmwg commented Mar 16, 2026

View reviewed changes

README_GITFLEXIMOD.md Outdated Show resolved Hide resolved

Apply suggestion from @slevis-lmwg

06b3fae

slevis-lmwg commented Mar 16, 2026

View reviewed changes

README_GITFLEXIMOD.md Outdated Show resolved Hide resolved

Apply suggestion from @slevis-lmwg

6f44d78

slevis-lmwg commented Mar 16, 2026

View reviewed changes

README_GITFLEXIMOD.md Outdated Show resolved Hide resolved

Apply suggestion from @slevis-lmwg

1e8ebd3

slevis-lmwg modified the milestones: cesm3.0.0 release branch tag, ctsm6.0.0 (code freeze) Mar 16, 2026

slevis-lmwg moved this from Todo to In Progress in LMWG: Sprint Planning Board Mar 16, 2026

Updates to README

748d1e8

slevis-lmwg added 5 commits March 17, 2026 17:57

Merge branch 'b4b-dev' into readmes_to_md

04bd3cc

Formatting corrections to markdown file

dbd84e7

Formatting update to the same markdown file (README_on_CTSM.md)

5649db2

Replace another README with README.md

6285c40

Replace one more README with README.md

cd5792f

slevis-lmwg added 7 commits March 19, 2026 14:42

Replace another README with README.md

4d863f6

Formatting correction to latest README.md

769a5b2

Formatting correction (2nd attempt)

91612e3

Formatting corrections (3rd)

80ca017

Formatting corrections (4th)

a972423

Formatting corrections (5th)

31641ba

Formatting corrections (6th)

2f40fb3

slevis-lmwg commented Mar 19, 2026

View reviewed changes

slevis-lmwg added 10 commits March 19, 2026 15:41

Replace README.unit_testing with README.unit_testing.md

f7463b8

Replace one more README with README.md

5b91272

Replace README.filecopies with README.filecopies.md

d8d58a7

Replace README.fsurdat_modifier, README.mesh_mask_modifier w md versions

1ca5c3e

Formatting corrections to the two most recenty committed .md files

9953a12

Formatting corrections (2nd)

190a95a

Putting back README.unit_testing

b02a4d2

Formatting corrections (3rd)

7973009

Merge branch 'b4b-dev' into readmes_to_md

aa651b9

Merge branch 'b4b-dev' into readmes_to_md

7838aba

slevis-lmwg requested a review from samsrabin March 19, 2026 23:50

slevis-lmwg moved this from In Progress to In review in CLM documentation Mar 19, 2026

slevis-lmwg commented Mar 20, 2026

View reviewed changes

samsrabin requested changes Mar 20, 2026

View reviewed changes

github-project-automation bot moved this from In progress - b4b-dev to Stalled (needs review, blocked etc.) in CTSM: Upcoming tags Mar 20, 2026

Conversation

slevis-lmwg commented Mar 16, 2026

Description of changes

Specific notes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

slevis-lmwg commented Mar 16, 2026

Uh oh!

ekluzek commented Mar 16, 2026

Uh oh!

slevis-lmwg commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

slevis-lmwg Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

slevis-lmwg commented Mar 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

samsrabin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

slevis-lmwg commented Mar 18, 2026 •

edited

Loading

slevis-lmwg Mar 19, 2026 •

edited

Loading